package com.aldobucchi.ds.container
{
	

	import com.aldobucchi.ds.IRDataStructure;
	
	
	public interface IRContainer extends IRDataStructure
	{
		
		
		/**
		 * 
		 * Returns true if this container contains the given element.
		 * 
		 * @param e
		 * @return 
		 * 
		 */		
		function contains( e:* ):Boolean;
		

		/**
		 * 
		 * Returns the multiplicity ( number of occurrences ) of element e within this container.
		 * If you just want to check for containment, it might be faster to use contains( ) ( depends on the implementation )
		 * 
		 * @param e
		 * @return 
		 * 
		 */
		function getMultiplicity( e:* ):uint;		
		
		
		
		
		/**
		 * 
		 * @param emptyValue
		 * 		The value to pass if the container is empty.
		 * 
		 * @return 
		 * 
		 */	
		function any( emptyValue:* = undefined ):*;
		
		
		
		
		
		// function toArray( ):Array;
		
		
		
		
		/**
		 * 
		 * The seame as toArray, but exposed as a getter
		 * to allow runtime debugging ( inspection of variables )
		 * 
		 * @return 
		 * 
		 */		
		function get asArray( ):Array;
		
		
		
		
		
		
		function get size( ):uint;



		/**
		 * 
		 * Walks the container structure using an internal algorithm.
		 * the function must have the following signature
		 * 
		 * walker( element:*, multiplicity:uint );
		 * 
		 * multiplicity is a positive integer.
		 * 
		 * the same element can happen multiple times. the total multiplicity is the sum all multiplicities
		 * 
		 * 
		 * @param walker
		 * 
		 */
		function walk( walker:Function ):void;
		
	}
	
	
}